." The first line of this file must contain the '"[e][r][t][v] line
." to tell man to run the appropriate filter "t" for table.
." vim: set filetype=nroff :
."
."	$Id$
."
."######################################################################
."#									#
."#			   Copyright (C)  2004				#
."#	     			Internet2				#
."#			   All Rights Reserved				#
."#									#
."######################################################################
."
."	File:		owampd.conf.man
."
."	Author:		Jeff Boote
."			Internet2
."
."	Date:		Tue May 11 14:15:18 MDT 2004
."
."	Description:	
."
.TH owampd.conf 5 "$Date$"
.SH NAME
owampd.conf \- One-way latency daemon configuration file.
.SH DESCRIPTION
The \fBowampd.conf\fR file is the configuration file for the owampd(8)
daemon. It is used to configure the basic operation of the server. For
example, what addresses and ports it should listen on, where it should
send error messages, and where it should save files.
.PP
The policy rules for \fBowampd\fR are configured using the \fBowampd.limits\fR
file; the details for configuring those policies are described in
the owampd.limits(5) manual page.
.PP
The format of this file is:
.RS
.IP \(bu
Comment lines are any line where the first non-whitespace character is '#'.
These lines are counted for the purposes of returning line numbers in error
messages but are otherwise ignored by \fBowampd\fR.
.IP \(bu
Lines may be continued using the semi-standard '\\' character followed
immediately by a newline character. This is the only valid place for
the '\\' character. If it is found elsewhere, a syntax error is reported.
.IP \(bu
Blank lines are treated as comment lines.
.IP \(bu
All other lines are used to set configuration options. The format of these
lines is an initial keyword followed by a variable list of arguments,
separated by whitespace.
.RE
.SH CONFIGURATION OPTIONS
.TP
.BI authmode " authmode"
Specify the authentication modes the server is willing to use for
communication. \fIauthmode\fR should be set as a character string, with
any or all of the characters "AEO". The modes are:
.RS
.IP \fBA\fR
[\fBA\fR]uthenticated. This mode encrypts the control connection and
encrypts part of each test packet.
.IP \fBE\fR
[\fBE\fR]ncrypted. This mode encrypts the control connection and encrypts
each test packet in full. This mode forces an encryption step between
the fetching of a timestamp and when the packet is sent. This adds more
computational delay to the time reported by \fBOWAMP\fR for each packet.
.IP \fBO\fR
[\fBO\fR]pen. No encryption of any kind is done.
.PP
The server can specify all the modes with which it is willing to communicate.
The most strict mode that both the server and the client are willing to use
will be selected.
.IP Default:
"AEO".
.RE
.TP
.BI controltimeout " controltimeout"
Number of seconds to wait for protocol messages before timing out.
.RS
.IP Default:
1800
.RE
.TP
.BI datadir " datadir"
Directory path where data files will be placed. The data files are the
"\fIreceive\fR" session files that are buffered on the server. Policy
restrictions can be used to set how much disk space a given connection
can use, as well as to determine when each file is deleted. (See the
\fBowampd.limits(f)\fR manual page.)
.RS
.IP Default:
Current directory
.RE
.TP
.BI dieby " dieby"
Number of seconds to wait for child processes to gracefully terminate
before killing them with \fBSIGKILL\fR. This is in response to the master
process receiving \fBSIGTERM\fR or \fBSIGHUP\fR.
.RS
.PP
This option should no longer be needed. If child processes are not exiting
gracefully, please send a bug report to owamp-users\@internet2.edu.
.IP Default:
30
.RE
.TP
.BI diskfudge " diskfudge"
Fudge factor to use when determining if a buffered owp file should be kept.
It creates a hard limit for disk usage. The soft limit is determined by
the \fIlimitclass\fR that a connection matches [see the owampd.limits(5)
manual page] and is applied when a test is requested. If the estimated
file-size of the test would put the
\fIlimitclass\fR over the soft limit, then the test is denied. However, it is
possible, due to duplicate packets, that a test session file may end up larger
than this estimate. If that happens, and if the file is successfully saved
to disk, then, upon completion of the test, the actual file-size is used to
update the disk usage in the resource broker process. At this point, the hard
limit is applied. The hard limit is determined by multiplying the soft limit
by the \fIdiskfudge\fR. If the final file-size causes the disk space
used by the \fIlimitclass\fR to be larger than the
quota defined by the hard limit then the file is immediately deleted.
.RS
.PP
A liberal factor
is recommended because this factor won't come in to play unless there are
numerous duplicates, and that is precisely the kind of data most users
will want to see. However, it is important to have this factor to ensure
disk usage is not too vulnerable to replay DOS attacks of the test protocol.)
.PP
The valid values for \fIdiskfudge\fR are 1.0-10.0.
.IP Default:
1.0 (hard limit is the same as the soft limit)
.RE
.TP
.BI enddelay " enddelay"
Amount of time for a sender to wait after session completion (last packet
send-time plus \fItimeout\fR) before sending the stop sessions message.

This is important if the sender clock is running ahead of the receiver clock.

A session is complete \fItimeout\fR after the send time of the final packet.
If the sender clock is ahead of the receivers clock, the sender will declare
the session complete before the receiver. The receiver
is only allowed to retain records for the packets that were sent at least
\fItimeout\fR before it receives the stop sessions message from
the sender. Therefore, if the sender clock is running ahead of the receiver
clock, the receiver will be forced to delete some number of the final
packets from the session.

This parameter directs the sender to wait \fIenddelay\fR after
session completion allowing the receiver clock to be essentially \fIenddelay\fR
later than the sender clock and still retain full sessions.
.RS
.IP Default:
1.0 (seconds)
.RE
.TP
.BI facility " facility"
Specify the syslog \fIfacility\fR to log messages.
.RS
.IP Default:
LOG_DAEMON
.RE
.TP
.BI group " group"
Specifies the gid the \fBowampd\fR process should run as. \fIgroup\fR
can be specified using a valid group name on the system or by using -gid.
This option is only used if \fBowampd\fR is started as root.
.RS
.PP
This option can be useful to limit log-file permissions to only users
in this group.
.RE
.TP
.B loglocation
Directs the \fBowampd\fR process to report source code file and line
number information with error messages. This is a particularly useful
option to set when sending in messages as part of a bug report.
.TP
.BI maxcontrolsessions " sessions"
Specifies the maximum number of control sessions that can be
active concurrently. Further connections will be closed until the
limit is no longer exceeded.
.RS
.IP Default:
0 - unlimited
.RE
.TP
.BI pbkdf2_count " count"
This indicates the count parameter for the pseudo-random key derivation
function that is used to derive the session key from the long term
key stored in the \fBowampd.pfs\fR file.
.RS
.IP Default:
2048
.RE
.TP
.B rootfolly
If present, this disables the requirement that \fBowampd\fR run with
non-root permissions. There are legitimate reasons to run \fBowampd\fR
as root, but it is more risky. (For example, some operating systems
require root permissions to set the TOS bits used by the \fI\-D\fR and
\fI\-H\fR options of \fBowping\fR.) This additional option was added
to ensure root permissions are only used when explicitly intended.
.TP
.BI srcnode " nodename:port"
Specify the address and port that \fBowampd\fR will listen for requests.
\fInodename\fR can be specified using a DNS name or using the textual
representation of the address. It is possible to set the source address
without setting the \fIport\fR by simply leaving off the ':' and \fIport\fR
specification. Likewise, a non-default port can be specified for
all system addresses (wildcard) by starting the specification string with
a ':'.  If an IPv6 address is specified, note that the accepted format
contains \fInodename\fR in square brackets as: [fe80::fe9f:62d8]. This
ensures the port number is distinct from the address specification. The
address can be wildcarded by only specifying the \fIport\fR portion.
.RS
.PP
Because the default port for \fBowampd\fR is in the \fIprotected\fR range
for most operating systems, it is usually required that \fBowampd\fR
is stared as root. This option can be used to specify a non-standard
port value that is not protected.
.IP Default:
\fInodename\fR is wildcarded as any currently available address
.br
\fIport\fR is 861.
.RE
.TP
.BI testports " 0 | lowport-highport"
Specify the specific port range to use on the local host for
.I OWAMP-Test
packets. This can be specified in two ways. First, as 0 which would indicate
.B owampd
should allow the system to pick the port (ephemeral). Second, as a range.
.I lowport
must be a smaller value than
.I highport
and both numbers must be valid port values. (16 bit unsigned integer values)
.RS
.IP Default:
0
.RE
.TP
.BI user " user"
Specifies the uid the \fBowampd\fR process should run as. \fIuser\fR
can be specified using a valid user name on the system or by using -uid.
This option is only used if \fBowampd\fR is started as root.
.RS
.PP
In the default case, \fBowampd\fR should be started as root so it can bind
the default port 861. (See \fIsrcnode\fR option.) \fBowampd\fR will release root
permissions shortly after binding to this protected port and requests will
be serviced by processes running with permissions defined by the \fIuser\fR.
.RE
.TP
.BI vardir " vardir"
Directory path where the owampd.pid and owampd.info files will be placed.
.RS
.IP Default:
Current directory
.RE
.TP
.B verbose
If this option is present, it directs the \fBowampd\fR process to
generate more verbose messages to syslog.
.SH SEE ALSO
owping(1), owampd(8), owampd.limits(5), owampd.pfs(5), pfstore(1),
and the \%http://e2epi.internet2.edu/owamp/ web site.
.SH ACKNOWLEDGMENTS
This material is based in part on work supported by the National Science
Foundation (NSF) under Grant No. ANI-0314723. Any opinions, findings and
conclusions or recommendations expressed in this material are those of
the author(s) and do not necessarily reflect the views of the NSF.
